home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 July: Mac OS SDK / Dev.CD Jul 97 SDK1.toast / Development Kits (Disc 1) / Apple Remote Access API / ARA Security API 1.0 / SecurityInterfaces / SecurityInterface.h next >
Encoding:
Text File  |  1993-11-03  |  15.5 KB  |  454 lines  |  [TEXT/MPS ]
  1. //234567890123456789012345678901234567890123456789012345678901234567890123456789
  2. //===========================================================================
  3. //    File:    SecurityInterface.h
  4. //
  5. //    This file is the header file which a third party security vendor can
  6. //    use to create an add-on security module.  The add-on security modules
  7. //    can be used to integrate a security device with Apple Remote Access.
  8. //
  9. //    Copyright © 1992, 1993 Apple Computer Inc.
  10. //    All rights reserved
  11. //
  12. //    Author:  Farzad Sarabi
  13. //
  14. //    Modification history:
  15. //
  16. //    9/29/1993    Farzad        Removed declarations for some routines that were
  17. //                            obsolete.
  18. //    2/15/1993    Farzad        The A5 world and a working environment is now
  19. //                            setup for the security modules.  As a result of
  20. //                            this some of the routines in this module are
  21. //                            obsolete.  Among these are ARAGet/SetMyPrivateData,
  22. //                            ARAGetMyResFile.
  23. //    10/6/1992    Farzad        Created
  24. //===========================================================================
  25.  
  26.  
  27. #ifndef SECURITY_INTERFACE
  28. #define SECURITY_INTERFACE 1
  29.  
  30. #ifndef __FILES__
  31. #include    <Files.h>
  32. #endif
  33.  
  34.  
  35. #ifndef SECURITY_PUBLIC
  36. #include    "SecurityPublic.h"
  37. #endif
  38.  
  39.  
  40. //===========================================================================
  41. //    Macros
  42. //===========================================================================
  43.  
  44. #define kSecurityInterfaceVersion 0x0100    // 0x0100 will be release 1
  45.  
  46.  
  47. #ifdef __cplusplus
  48. extern "C"    {                // in case we are linking into C++ code
  49. #endif
  50.  
  51.  
  52.  
  53. //===========================================================================
  54. //    Types
  55. //===========================================================================
  56.  
  57. // actions are defined in the SecurityPublic.h file
  58. // ARAErr is defined in SecurityPublic.h
  59. // SecurityEntryProc is defined in SecurityPublic.h
  60. // SecurityCompletionProc is defined in SecurityPublic.h
  61.  
  62. //===========================================================================
  63. //    Data
  64. //===========================================================================
  65.  
  66.  
  67. //===========================================================================
  68. //    Functions
  69. //===========================================================================
  70.  
  71. // the following are functions you can call to have AppleTalk Remote Access
  72. // perform these services
  73.  
  74.  
  75.  
  76. extern pascal ARAErr    ARARead( SecurityReference        MyReference,
  77.                                  void                    * DataPtr,
  78.                                  int                    DataSize,
  79.                                  SecurityCompletionProc    CompletionProc,
  80.                                  long                    CompletionParam );
  81. //===========================================================================
  82. //    Description:    this routine is used to post an asynchronous read
  83. //                    operation for data coming from the remote machine.
  84. //                    This routine can be used by line-level and protocol-level
  85. //                    authentication modules.  It is not available for 
  86. //                    configuration modules.
  87. //
  88. //    Parameters:        MyReference        this module's unique reference
  89. //                    DataPtr            where to put the read data
  90. //                    DataSize        the maximum number of bytes to read
  91. //                    CompletionProc    this routine will be called when the
  92. //                                    read request has finished
  93. //                    CompletionParam    this is information you can provide to
  94. //                                    be passed to the completion proc
  95. //
  96. //    Return Value:    ARAErr            result code, nonzero indicates an error
  97. //
  98. //    Creation Date:    10/6/1992
  99. //
  100. //    Modifications:
  101. //
  102. //===========================================================================
  103.  
  104.  
  105.  
  106. extern pascal ARAErr    ARAWrite( SecurityReference            MyReference,
  107.                                   void                        * DataPtr,
  108.                                   int                        DataSize,
  109.                                   SecurityCompletionProc    CompletionProc,
  110.                                   long                        CompletionParam );
  111. //===========================================================================
  112. //    Description:    this routine is used to asynchronously write data to
  113. //                    the remote machine.  It can be used by line-level and
  114. //                    protocol-level authentication modules.
  115. //
  116. //    Parameters:        MyReference        your unique reference
  117. //                    DataPtr            the data to be written out
  118. //                    DataSize        the amount of data to write
  119. //                    CompletionProc    this routine is called when the data
  120. //                                    has been written out
  121. //                    CompletionParam    this is extra information you can provide
  122. //                                    to be passed to the CompletionProc
  123. //
  124. //    Return Value:    ARAErr            result code, nonzero indicates an error
  125. //
  126. //    Creation Date:    10/6/1992
  127. //
  128. //    Modifications:
  129. //
  130. //===========================================================================
  131.  
  132.  
  133.  
  134. extern pascal ARAErr ARALogMessage( SecurityReference        MyReference,
  135.                                     char                    * Message,
  136.                                     SecurityCompletionProc    CompletionProc,
  137.                                     long                    CompletionParam );
  138. //===========================================================================
  139. //    Description:    you can use this routine to put a message in AppleTalk
  140. //                    remote accesses log file.
  141. //
  142. //    Parameters:        MyReference        your unique reference
  143. //                    Message            a Pascal string which will be logged to
  144. //                                    in the log file
  145. //                    CompletionProc    this routine will be called when the
  146. //                                    log message has been completed.
  147. //                    CompletionParam    additional information you can supply to
  148. //                                    be passed on to the completion proc
  149. //
  150. //    Return Value:    ARAErr            result code, nonzero indicates an error
  151. //
  152. //    Creation Date:    10/6/1992
  153. //
  154. //    Modifications:
  155. //
  156. //===========================================================================
  157.  
  158.  
  159.  
  160. extern pascal ARAErr ARACallBackAt( SecurityReference        MyReference,
  161.                                     char                    * DialString,
  162.                                     SecurityCompletionProc    CompletionProc,
  163.                                     long                    CompletionParam );
  164. //===========================================================================
  165. //    Description:    this routine can be used during authentication to
  166. //                    cause the server to call the client back at the
  167. //                    specified number.
  168. //
  169. //    Parameters:        MyReference        your unique reference
  170. //                    DialString        this is a pascal string which must
  171. //                                    contain a dial string for the number
  172. //                                    to call the client back at
  173. //                    CompletionProc    this proc will be called when the callback
  174. //                                    has been completed.
  175. //                    CompletionParam    additional information you can provide
  176. //                                    that will be passed to the CompletionProc
  177. //
  178. //    Return Value:    ARAErr            result code, nonzero indicates an error
  179. //
  180. //    Creation Date:    10/6/1992
  181. //
  182. //    Modifications:
  183. //
  184. //===========================================================================
  185.  
  186.  
  187.  
  188. extern pascal ARAErr  ARAAllowUser( SecurityReference        MyReference,
  189.                                     SecurityCompletionProc    CompletionProc,
  190.                                     long                    CompletionParam );
  191. //===========================================================================
  192. //    Description:    the authentication code on the server can call this
  193. //                    routine to indicate the user has passed this module's
  194. //                    security requirements.
  195. //
  196. //    Parameters:        MyReference        your unique reference
  197. //                    CompletionProc    this routine is called when AppleTalk
  198. //                                    Remote Access has finished handling
  199. //                                    your authentication information.
  200. //
  201. //    Return Value:    ARAErr            result code, nonzero indicates an error
  202. //
  203. //    Creation Date:    10/6/1992
  204. //
  205. //    Modifications:
  206. //
  207. //===========================================================================
  208.  
  209.  
  210.  
  211. extern pascal ARAErr  ARADontAllowUser( SecurityReference        MyReference,
  212.                                         char                    * Message,
  213.                                         SecurityCompletionProc    CompletionProc,
  214.                                         long                    CompletionParam );
  215. //===========================================================================
  216. //    Description:    the server security module can call this routine to
  217. //                    prevent a user from being allowed in.
  218. //
  219. //    Parameters:        MyReference        your unique reference
  220. //                    Message            a pascal string stating why the user
  221. //                                    was not allowed access
  222. //                    CompletionProc    this routine will be called when the
  223. //                                    request for not allowing user has bee
  224. //                                    processed
  225. //                    CompletionParam    additional information you can provide
  226. //                                    which will be passed to the completion
  227. //                                    proc
  228. //
  229. //    Return Value:    ARAErr            result code, nonzero indicates an error
  230. //
  231. //    Creation Date:    10/6/1992
  232. //
  233. //    Modifications:
  234. //
  235. //===========================================================================
  236.  
  237.  
  238.  
  239.  
  240. extern pascal ARAErr  ARAReadSecurityData( SecurityReference    MyReference,
  241.                                            void                    * DataPtr,
  242.                                            int                    DataSize,
  243.                                     SecurityCompletionProc        CompletionProc,
  244.                                            long                    CompletionParam );
  245. //===========================================================================
  246. //    Description:    this routine can be used to read data for this security
  247. //                    module which is associated with either a user (on the
  248. //                    server side), or a connection (on the client side).
  249. //                    This routine doesn't lock the data, so use it only when
  250. //                    you just plan to read the data.
  251. //
  252. //    Parameters:        MyReference        your unique reference
  253. //                    DataPtr            where the data will be read to
  254. //                    DataSize        maximum number of bytes to read
  255. //                    CompletionProc    this routine will be called when the
  256. //                                    read request has completed
  257. //                    CompletionParam    additional information you can provide
  258. //                                    to be passed to the completion proc
  259. //
  260. //    Return Value:    ARAErr            result code, nonzero indicates an error
  261. //
  262. //    Creation Date:    10/6/1992
  263. //
  264. //    Modifications:
  265. //
  266. //===========================================================================
  267.  
  268.  
  269.  
  270. extern pascal ARAErr ARAReadLockSecurityData( SecurityReference    MyReference,
  271.                                               void                * DataPtr,
  272.                                               int                DataSize,
  273.                                         SecurityCompletionProc    CompletionProc,
  274.                                               long                CompletionParam );
  275. //===========================================================================
  276. //    Description:    this routine can be used to read security data and lock
  277. //                    it to be modified.  If you are planning on modifying your
  278. //                    data and then writing it, you must call this routine.
  279. //                    It locks the data until the a ARAUnlockSecurityData call.
  280. //
  281. //    Parameters:        MyReference        your unique reference
  282. //                    DataPtr            where the data will be read
  283. //                    DataSize        the maximum number of bytes to read
  284. //                    CompletionProc    this routine will be called when the
  285. //                                    data is read into your buffer.
  286. //                    CompletionParam    additional information you can provide to
  287. //                                    be passed on to the CompletionProc.
  288. //
  289. //    Return Value:    ARAErr            result code, nonzero indicates an error
  290. //
  291. //    Creation Date:    10/29/1992
  292. //
  293. //    Modifications:
  294. //
  295. //===========================================================================
  296.  
  297.  
  298.  
  299.  
  300. extern pascal ARAErr    ARAUnlockSecurityData( SecurityReference    MyReference,
  301.                                             SecurityCompletionProc    CompletionProc,
  302.                                                long                    CompletionParam );
  303. //===========================================================================
  304. //    Description:    if you have read the security data with ARAReadLockSecurityData
  305. //                    you must call this routine to unlock the data.  After this
  306. //                    call others can then lock the security data.
  307. //
  308. //    Parameters:        MyReference        your unique reference
  309. //                    CompletionProc    this routine is called when the data is unlocked
  310. //                    CompletionParam    additiona information you can provide to be
  311. //                                    passed to the CompletionProc
  312. //
  313. //    Return Value:    ARAErr            result code, nonzero indicates an error
  314. //
  315. //    Creation Date:    10/29/1992
  316. //
  317. //    Modifications:
  318. //
  319. //===========================================================================
  320.  
  321.  
  322.  
  323. extern pascal ARAErr ARAWriteSecurityData( SecurityReference    MyReference,
  324.                                            void                    * DataPtr,
  325.                                            int                    DataSize,
  326.                                        SecurityCompletionProc CompletionProc,
  327.                                            long                CompletionParam );
  328. //===========================================================================
  329. //    Description:    this routine can be used by the module to write private
  330. //                    data which is either associated with a user (on the server
  331. //                    side), or a connection (on the client side).
  332. //
  333. //    Parameters:        MyReference        your unique reference
  334. //                    DataPtr            the data to be written out
  335. //                    DataSize        the amount of data to write out
  336. //                    CompletionProc    this routine is called when AppleTalk
  337. //                                    Remote Access has completed the write
  338. //                                    operation
  339. //                    CompletionParam    additional information you can provide
  340. //                                    which is passed to the completion proc
  341. //
  342. //    Return Value:    ARAErr            result code, nonzero indicates an error
  343. //
  344. //    Creation Date:    10/6/1992
  345. //
  346. //    Modifications:
  347. //
  348. //===========================================================================
  349.  
  350.  
  351.  
  352. extern pascal ARAErr    ARAGetUserInfo( SecurityReference    MyReference,
  353.                                         void                * DataPtr,
  354.                                         int                    DataSize,
  355.                                     SecurityCompletionProc    CompletionProc,
  356.                                         long                CompletionParam );
  357. //===========================================================================
  358. //    Description:    this routine can be called to get information about the
  359. //                    the user, such as user name etc.  It is an asynchronous
  360. //                    call.
  361. //
  362. //    Parameters:        MyReference        your unique code reference
  363. //                    DataPtr            pointer to where the user's name (Pascal
  364. //                                    string) will be stored
  365. //                    DataSize        maximum number of bytes to read
  366. //                    CompletionProc    this routine will be called when the call
  367. //                                    has completed
  368. //                    CompletionParam    additional information to be passed to
  369. //                                    the CompletionProc
  370. //
  371. //    Return Value:    ARAErr            result code, nonzero indicates an error
  372. //
  373. //    Creation Date:    10/6/1992
  374. //
  375. //    Modifications:
  376. //
  377. //===========================================================================
  378.  
  379.  
  380.  
  381.  
  382. extern pascal long    ARAGetMySessionRef( SecurityReference    MyReference );
  383. //===========================================================================
  384. //    Description:    You can call this routine to obtain the session reference
  385. //                    for the connection for which your code is loaded.  This
  386. //                    value is unique and stays the same during the connection.
  387. //                    If you have a security module which has both a line-level
  388. //                    and a protocol-level authentication, you can use this
  389. //                    unique reference as a key to communicate between the
  390. //                    code resources.
  391. //
  392. //    Parameters:        MyReference        this is your code's unique reference
  393. //
  394. //    Return Value:    long            the session reference, NULL if there is an
  395. //                                    error
  396. //
  397. //    Creation Date:    10/29/1992
  398. //
  399. //    Modifications:
  400. //
  401. //===========================================================================
  402.  
  403.  
  404.  
  405.  
  406. extern pascal ARAErr    ARATickleMe( SecurityReference        MyReference,
  407.                                      long                    TickleParam );
  408. //===========================================================================
  409. //    Description:    this routine can be used to have AppleTalk Remote Access
  410. //                    call your entry routine with a kSecurityTickleAction.
  411. //                    You can also provide some additional information which
  412. //                    is passed to the entry routine.
  413. //
  414. //    Parameters:        MyReference        your unique reference
  415. //                    TickleParam        additional information you can provide
  416. //                                    which is passed to the entry proc
  417. //
  418. //    Return Value:    ARAErr            result code, nonzero indicates an error
  419. //
  420. //    Creation Date:    10/6/1992
  421. //
  422. //    Modifications:
  423. //
  424. //===========================================================================
  425.  
  426.  
  427.  
  428. extern pascal ARAErr ARACompleteOperation( SecurityReference     MyReference );
  429. //===========================================================================
  430. //    Description:    this routine can be called to terminate an operation.
  431. //                    It causes ARA to send a kSecurityEnd action.  During
  432. //                    configuration for example the code resource can call
  433. //                    this routine to indicate that configuration has
  434. //                    completed.
  435. //
  436. //    Parameters:        MyReference        your unique reference
  437. //
  438. //    Return Value:    ARAErr            result code, nonzero indicates an error
  439. //
  440. //    Creation Date:    10/6/1992
  441. //
  442. //    Modifications:
  443. //
  444. //===========================================================================
  445.  
  446.  
  447.  
  448. #ifdef __cplusplus
  449. }
  450. #endif
  451.  
  452.  
  453. #endif // SECURITY_INTERFACE
  454.